home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / c_eval.zip / EE.DOC < prev    next >
Text File  |  1993-04-23  |  8KB  |  193 lines
  1. EE - Expression Evaluator                                       January 1992
  2.  
  3. By:     Mark Morley
  4.         3889 Mildred Street
  5.         Victoria, B.C.  Canada
  6.         V8Z 7G1
  7.         (604) 479-7861
  8.  
  9. As it is noted in the source code, you are free to do anything you desire
  10. with this code, as long as you give credit where credit is due...  For
  11. criticism, fixes, suggestions, enhancements, job offers, etc, send E-Mail to
  12.  
  13.         morley@Camosun.BC.CA
  14.  
  15. I will do my best to fix any reported bugs and incorporate any suggestions,
  16. but since this isn't exactly what I get paid for, I have to do it on my own
  17. free time... ;)
  18.  
  19. Please let me know how you like this program and how you use it, this is my
  20. first "public" submission of code and I'd really appreciate any feedback.
  21.  
  22.  
  23. OK, here we go...
  24.  
  25. The EE module provides a handful of 'C' routines that allow you to incorporate
  26. mathematical expression evaluation into your programs.  For example, using
  27. these routines you can evaluate such expressions as:
  28.  
  29.         1+1
  30.         10 * (x=5)                 <== Assigns 5 to X first!
  31.         ((1/3) * sin(45))^2
  32.         X=50
  33.         Y=100
  34.         z=hypot(x,y)
  35.  
  36. As you can see, it supports variable assignments and referencing, as well as
  37. functions.  Variable and function names are limited to 16 characters in length,
  38. but this is easily modified in the .H file.  Functions may have anywhere from
  39. 1 to 3 arguments, again this is modifiable.
  40.  
  41. It also maintains a set of "read-only variables" (constants) that can be
  42. referenced just like variables, but they cannot be permanently altered by
  43. the user.  Constants are defined by you in the EE.C file.
  44.  
  45. *** ATTENTION VMS USERS: If you assign or reference a variable that begins
  46. with an underscore character (_), the assignment/reference applies to an
  47. external DCL symbol.  For example:  If you type EE x=1.3 at the DCL prompt,
  48. EE will set an internal variable called X to the value of 1.3  However, if
  49. you type EE _x=1.3 at the DCL prompt, EE will create (or reassign) a DCL
  50. symbol called X (<== note there is *no* underscore here!) and give it the
  51. value of 1.3  Since DCL does not support floating point symbols directly, 
  52. this symbol will be in string format.  If it is referenced in a subsequent
  53. invocation, its value will be converted back to a floating point value
  54. internally.  Keep in mind that this *can* lead to truncation/precision 
  55. errors...  You cannot use EE to delete a DCL symbol.
  56.  
  57.  
  58. The EE.C file includes a main() routine that implements a simple calculator
  59. that works the following way...
  60.  
  61. If you supply any command line arguments to EE, it will concatenate them all
  62. into one string and attempt to evaluate them.  This saves you from having to
  63. put quotes around expressions that contain spaces.  If the evaluation is
  64. successful, the answer is displayed.  If an error is encountered a message is
  65. displayed.
  66.  
  67. If no command line arguments are passed, then EE goes into an interactive
  68. mode and displays the EE> prompt.  Anything typed at this prompt is evaluated
  69. as an expression with the exception of the following keywords:
  70.  
  71.         EXIT       Exits the program.
  72.         VARS       Shows a list a variables and their values.
  73.         CONS       Shows a list of constants and their values.
  74.         CLR        Erases all variables.
  75.  
  76. In itself EE.EXE may be a useful utility to you and you are free to use and
  77. distribute it...
  78.  
  79.  
  80. NOTE:  These routines are somewhat recursive, so you'd better have a decent
  81.        amount of stack space (for those of you who worry about such things)
  82.        Obviously, the more parenthesis, function calls, etc. that are in
  83.        your expressions, the more recursion that takes place.  There is no
  84.        built-in checking for maximum recursion depths, etc.
  85.  
  86. Although a certain amount of syntactic error checking is done, overflows
  87. and other math errors are left for you to catch with the matherr() function.
  88. Also, depending on the "inner workings" of your C compiler's floating point
  89. routines, you may experience small losses of precision.  For example: On my
  90. 486 running DOS and using BORLAND C++, the result of 1+0.9999 is 1.9999 but
  91. the result of 1+0.99999 comes out as 2.  This can be fixed in various ways
  92. but I leave it to you for now...
  93.  
  94.  
  95. Operator Precedence
  96. ===================
  97.  
  98. This routine handles the following "operators" in the following priority:
  99. 1) Anything enclosed in ()'s as well as variables and functions.
  100. 2) Unary + and - signs
  101. 3) "To the power of" symbol: ^
  102. 4) Times (*), divide (/), and modulus (%)
  103. 5) Plus (+) and minus (-)
  104. 6) Assignments (=)
  105.  
  106.  
  107. The callable routines in EE.C are as follows:
  108.  
  109. Evaluate( char* e, double* r, int* a )
  110. ==============================
  111.  
  112. Where:
  113.     e is a math expression to evaluate (in the form of a string)
  114.     r is a pointer to a place to store the result
  115.     a is a pointer to a flag
  116.  
  117.     This function evaluates the expression and passes back the result.  If the
  118.     evaluation is successful, a value of E_OK (0) is returned.  If the
  119.     expression happened to be a top-level assignment, then a value of 1 will
  120.     be returned in A, otherwise a value of 0 will be placed here.  Other return
  121.     values are:
  122.  
  123.         E_SYNTAX  (1)  Syntax error
  124.         E_UNBALAN (2)  Unbalanced parenthesis
  125.         E_DIVZERO (3)  Attempted division by zero
  126.         E_UNKNOWN (4)  Reference to unknown variable
  127.         E_MAXVARS (5)  Maximum variables exceeded
  128.         E_BADFUNC (6)  Unrecognised function
  129.         E_NUMARGS (7)  Wrong number of arguments to function
  130.         E_NOARG   (8)  Missing an argument to a function
  131.         E_EMPTY   (9)  Empty expression
  132.  
  133.     If a value other than E_OK is returned, then you can use the following
  134.     global variables to report the error:
  135.  
  136.         int   ERROR    The error code (as above)
  137.         char* ERANC    A pointer to the original expression
  138.         int   ERPOS    The position in the expression where the error happened
  139.         char* ERTOK    The token (symbol) that caused the error
  140.  
  141.  
  142. ClearAllVars()
  143. ==============
  144.  
  145.     This function erases all user-defined variables.  It should be called
  146.     at least once at the beginning of your program, before trying to evaluate
  147.     anything.
  148.  
  149.  
  150. ClearVar( char* n )
  151. ===================
  152.  
  153. Where:
  154.     n is the name of a variable
  155.  
  156.     This function erases a specific user-defined variable.  A value of 1 is
  157.     returned if the variable existed, a 0 if it didn't.
  158.     VMS Users: This has no effect on DCL symbols
  159.  
  160.  
  161. GetValue( char* n, double* v )
  162. ==============================
  163.  
  164. Where:
  165.      n is the name of a variable
  166.      v is a pointer to the place to put the value
  167.  
  168.      This function looks up the specified variable and passes back its value.
  169.      If the variable is found, it returns a 1, otherwise it returns a 0
  170.  
  171.  
  172. SetValue( char* n, double v )
  173. =============================
  174.  
  175. Where:
  176.      n is the name of a variable
  177.      v is a numeric value
  178.  
  179.      This function creates a new user-defined variable.  If the variable
  180.      already exists, its current value is replaced with the new value.
  181.  
  182.      A value of 1 is returned if it is successful, a 0 if there is no more
  183.      room for variables.
  184.  
  185.      It should be noted here that an expression like A=1+1, passed to
  186.      Evaluate(), will result in this function being called.  Note also that
  187.      an expression like A= will result in the variable A being erased.
  188.  
  189. Enjoy!
  190.  
  191. MARK
  192.  
  193.